SSO Introduction

This process details using VoiceCheck and the Maintenance & Inspection app with OAuth2-based single sign on. The OAuth provider is a third-party and the provider can be selected from any that meet the standards.

How It Works

SSO is configured during the installation for the VoiceCheck server and must also be configured within the Android M&I app.

VoiceCheck Server

Login

When the VoiceCheck server is configured with SSO authentication over basic authentication, VoiceCheck no longer manages user credentials and passwords. Instead, VoiceCheck relies on the user being logged onto their provider. When a user tries to access VoiceCheck:

  • If the user is logged onto their provider and is an authorized user in VoiceCheck, the VoiceCheck interface opens
  • If the user is not logged onto their provider, the user is directed to the provider logon page, then directed back to VoiceCheck after a successful logon.
  • If the user is not logged onto their provider, the user is directed to the provider logon page, then directed to a VoiceCheck error page after an unsuccessful logon.
  • If a user is logged onto their provider, but is not an authorized VoiceCheck, the user is directed to a VoiceCheck error page.

Logout

The logout link is still provided within the upper right corner of the VoiceCheck interface. Logout behavior depends if the SSO_Logout_Url has been configured.

If SSO_Logout_Url is configured, the user should be directed to the to the endpoint of their OAuth provider where the user can choose:

  • Yes - To logout from the OAuth provider. The user would have to log onto the OAuth provider again to use VoiceCheck.
  • No - The user is directed back to VoiceCheck and they remain logged into their OAuth provider. The user would not be required to log in again to use VoiceCheck.

If SSO_Logout_Url is not configured, the user's VoiceCheck session is ended. if the user tries to access VoiceCheck again, the user's status with the OAuth provider would be checked and may require a login if their session has expired.

VoiceCheck does not listen for logouts at the OAuth provider’s end. A user could be logged out of their OAuth provider but would remain logged into VoiceCheck.

User / Operator Management

With SSO authentication all password related entries are removed from the Create/Edit User and Create/Edit Operator screens.

The only item that can be edited on the profile screen is the email field. if theprofile is updated, the user is logged out as VoiceCheck and directed to the SSO logout page. However, the user still maintains the session with the identity provider. If the user tries to log back into VoiceCheck there is no SSO credential entry necessary.

When importing users/operators into an SSO-enabled instance of VoiceCheck the forced password reset prompt does not occur.

System Configuration

With SSO authentication the following items are removed from the System Configuration screen:

  • User Authentication
  • LDAP Configuration
  • Password Expiration Settings

Inspection Application

Sign On

The mobile app acquires an access token from the OAuth provider. This token is sent in place of the user password. See M&I App for configuration details.

When logging on, the user is directed to an intermediate screen in the M&I app and must click Ready to be directed to a sign on screen with the identity provider. After that screen is completed successfully, the user is returned to the M&I application.

Take a Break

When the user selects take a break, they are prompted for the break type. With SSO enabled, the user does not log out when taking a break and therefore does not have to log on after the break ends. Instead the user selects Ready from the Return From Break screen.

Session Timeout

When the SSO session times out, the user is directed to an intermediate screen in the M&I app and must click Ready to be directed to a sign on screen with the identity provider. After that screen is completed successfully, the user is returned to the M&I application.

Logout

When the user selects sign off the behavior depends on configuration.

  • If a logout endpoint has been specified, the user is logged out from VoiceCheck and their identity provider.
  • If a logout endpoint has not been specified, the user is not logged out from the identity provider. The user can access the app again without needing to log into the identity provider again.

A700x

The A700x does not support single sign on.

Web Services

REST Web Services

Under basic authentication, each request was required to provide authentication details (username and password).

With SSO, these calls must authenticate with an access token.

Failed validations are reported in the notifications table, viewable by selecting Administration > Notifications.

Authorization Header

  • The Authorization header defines the scheme used
  • Auth scheme is limited to JWT and bearer

Sample Authorization Header

'authorization: JWT eyJhbGciOiJSUzI1NiIsInR5cCI6I'
'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6I'

User Header

  • User must be registered in VoiceCheck
  • User must be registered in Provider
  • Token must belong to provided user
  • Requests with invalid tokens are rejected
  • Requests with expired tokens are rejected
  • Only JWT tokens are accepted. Opaque are not supported
  • User should have Web services role in order to access REST API

Sample User Header

 'user: joe'

Customer Header

  • Must include the name of a user already registered with VoiceCheck
  • The access token in the Authorization header must belong to this user

SOAP Web Services

SOAP web services are not supported in an SSO environment.